# Xoron Encoder Library Description

This document outlines the encoding Xoron library. The purpose of this document is to give general guidelines on how to encode and decode files and stream of bytes based on a secret password.

## Definitions

The Xoron encoder library header has the following definitions.

[comment]: <> (../inc/xrn_encoder.h)
```Xoronos_C
#ifndef STD_ENCODER_LIB_H
#define STD_ENCODER_LIB_H
```

The library includes the following headers.

[comment]: <> (../inc/xrn_encoder.h)
```Xoronos_C
#include <stdio.h>
#include <stdint.h>
#include <stdlib.h>
#include <string.h>
#include "xrn_common.h"
#include "xrn_arithmetic_backend.h"
```

The following define is used to initialize the magic number for the encoding parameters file.

[comment]: <> (../inc/xrn_encoder.h)
```Xoronos_C
#define XRN_ENC_MAGIC_NUM 0x22022022
```

The following define is used to handle the password buffer size.

[comment]: <> (../inc/xrn_encoder.h)
```Xoronos_C
#define XRN_ENC_PASS_BUFF_SIZE 256
```

The following define is used to handle the buffer size for probabilistic checks.

[comment]: <> (../inc/xrn_encoder.h)
```Xoronos_C
#define XRN_BUFFER_ENC_BIST_SIZE 128
```

The following defines are used as default threshold values for probability checks.

[comment]: <> (../inc/xrn_encoder.h)
```Xoronos_C
// 4.5 * 8
#define XRN_ENC_MAX_CONS_01_ERR_TH ( 36 )
// 4 * 8
#define XRN_ENC_MAX_CONS_01_WAR_TH ( 32 )
// XRN_BUFFER_ENC_BIST_SIZE * 5.5
#define XRN_ENC_MAX_AVG_01_ERR_TH  ( 704 )
// XRN_BUFFER_ENC_BIST_SIZE * 5.0
#define XRN_ENC_MAX_AVG_01_WAR_TH  ( 640 )
```

## Enumerations definition

### xrn_lib_xtype_t 

The **xrn_lib_xtype_t** is used to identify how to initialize the initial encoding/decoding parameters.

[comment]: <> (../inc/xrn_encoder.h)
```Xoronos_C
typedef enum {
    std_parameters = 0,
    xrn_parameters = 1,
    std_parameters_plus_password = 2,
    xrn_parameters_plus_password = 3,
    std_parameters_plus_file = 4,
    xrn_parameters_plus_file = 5,
    no_encoding = 6
} xrn_encoding_mode_t;
```

The **std_parameters** if the compiled std_parameters need to be used to initialize the encoding/decoding paramethers.

The **std_parameters_plus_password** if the compiled std_parameters plus the password need to be used to initialize the encoding/decoding paramethers.

The **std_parameters_plus_file** if the compiled std_parameters plus the file need to be used to initialize the encoding/decoding paramethers.

The **xrn_parameters** if only the xrn_parameters stored in a file are used to initialize the encoding/decoding paramethers.

The **xrn_parameters_plus_password** if the xrn_parameters stored in a file plus the password need to be used to initialize the encoding/decoding paramethers.

The **xrn_parameters_plus_file** if the xrn_parameters stored in a file plus the file need to be used to initialize the encoding/decoding paramethers.

The **no_encoding** if the xrn_parameters should be initialized to zero.


### xrn_check_initialization_mode_t 

The **xrn_check_initialization_mode_t** is used to specify the initialization mode for the probabilistic checks.

[comment]: <> (../inc/xrn_encoder.h)
```Xoronos_C
typedef enum {
    xrn_automatic = 0, 
    xrn_manual = 1,
} xrn_check_initialization_mode_t;
```

The **xrn_automatic** field is used to initialize the settings automatically.

The **xrn_manual** field is used to initialize the settings manually.

## Data Structures

### xrn_encoding_checks_t

The **xrn_encoding_checks_t** is used to store internal paramethers for both xrn_encode and xrn_decode safety checks.

[comment]: <> (../inc/xrn_encoder.h)
```Xoronos_C
typedef struct xrn_encoding_checks_t {
    uint8_t index;
    uint8_t buffer[XRN_BUFFER_ENC_BIST_SIZE];
    uint8_t buffer_full;
    uint8_t check_running_error_en;
    uint8_t check_disparity_error_en;
    uint32_t max_consecutives_01s_threshold_error;
    uint32_t max_consecutives_01s_threshold_warning;
    uint32_t max_number_of_01s_threshold_error;
    uint32_t max_number_of_01s_threshold_warning;
    uint32_t count_1;
    uint32_t count_0;
    uint32_t count_consecutive_1;
    uint32_t count_consecutive_0;
    uint32_t max_consecutive_1;
    uint32_t max_consecutive_0;
} xrn_encoding_checks_t;
```

The **index** field is address element in the buffer.

The **buffer** field is the buffer used for the safety checks.

The **buffer_full** field is a flag used to indicate if the buffer is full.

The **check_running_error_en** field is an enable used for the running errors checks.

The **check_disparity_error_en** field is an enable used for the average errors checks.

The **max_consecutives_01s_threshold_error** field is the threshold for the error of the number of consecutives zeroes or ones.

The **max_consecutives_01s_threshold_warning** field is the threshold for the warning of the number of consecutives zeroes or ones.

The **max_number_of_01s_threshold_error** field is the threshold of the maximum number of zeroes or ones in the buffer error.

The **max_number_of_01s_threshold_warning** field is the threshold of the maximum number of zeroes or ones in the buffer warning.

The **count_1** field is the counter used to keep track of the number of ones in the buffer.

The **count_0** field is the counter used to keep track of the number of zeroes in the buffer.

The **count_consecutive_1** field is the counter used to keep track of the consecutive number of ones in the buffer.

The **count_consecutive_0** field is the counter used to keep track of the consecutive number of zeroes in the buffer.

The **max_consecutive_1** field is used to keep track of the max consecutive number of ones observed.

The **max_consecutive_0** field is used to keep track of the max consecutive number of zeroes observed.

### xrn_encoding_param_t

The **xrn_encoding_param_t** is used to store internal paramethers for both xrn_encode and xrn_decode functions.

[comment]: <> (../inc/xrn_encoder.h)
```Xoronos_C
typedef struct xrn_encoding_param_t {
    uint8_t table[256];
    uint64_t prng_state[4];
    xrn_encoding_checks_t prob_checks;
} xrn_encoding_param_t;
```

The **table** field is the encoding table.

The **prng_state** field is the pseudo random number generation state.

### xrn_encoding_tmp_param_t

The **xrn_encoding_tmp_param_t** is used to store temporary and internal paramethers for both xrn_encode and xrn_decode functions.

[comment]: <> (../inc/xrn_encoder.h)
```Xoronos_C
typedef struct xrn_encoding_tmp_param_t {
    int i,j,k,ret,final_ret;
    uint8_t hidden_index_prng, hidden_index_input;
    uint8_t exposed_data_prng, hidden_data_input;
    uint8_t pseudo_random_seed;
    uint64_t t;
    uint8_t byte_tmp;
} xrn_encoding_tmp_param_t;
```

### xrn_encoding_settings_t

The **xrn_encoding_settings_t** is used to store interface parameters for input output operation.

[comment]: <> (../inc/xrn_encoder.h)
```Xoronos_C
typedef struct xrn_encoding_settings_t {
    FILE * encoding_parameters_fp;
    FILE * initialization_file_fp;
    xrn_encoding_mode_t mode;
    char password[XRN_ENC_PASS_BUFF_SIZE];
    uint16_t password_length;
    xrn_check_initialization_mode_t check_mode;
    uint8_t check_running_error_en;
    uint8_t check_disparity_error_en;
    uint32_t max_consecutives_01s_threshold_error;
    uint32_t max_consecutives_01s_threshold_warning;
    uint32_t max_number_of_01s_threshold_error;
    uint32_t max_number_of_01s_threshold_warning;
} xrn_encoding_settings_t;
```

The **encoding_parameters_fp** field is the file pointer to encoding parameters. The field is used if the mode is either xrn_parameters_plus or xrn_parameters_plus_password.

The **mode** field is the initialization mode for the encoding parameters.

The **password** field is the password used to generate the encoding parameters. The field is used if the mode is either xrn_parameters_plus_password or std_parameters_plus_password.

The **initialization_file_fp** field is the file used to generate the encoding parameters. The field is used if the mode is either xrn_parameters_plus_file or std_parameters_plus_file.

The **password_length** field is used to indicate the length of the password.

The **check_mode** field is used to initialize the probabilistic checks in either manual or automatic mode.

The **check_running_error_en** field is an enable used for the running errors checks.

The **check_disparity_error_en** field is an enable used for the average errors checks.

The **max_consecutives_01s_threshold_error** field is the threshold for the error of the number of consecutives zeroes or ones.

The **max_consecutives_01s_threshold_warning** field is the threshold for the warning of the number of consecutives zeroes or ones.

The **max_number_of_01s_threshold_error** field is the threshold of the maximum number of zeroes or ones in the buffer error.

The **max_number_of_01s_threshold_warning** field is the threshold of the maximum number of zeroes or ones in the buffer warning.

### xrn_encoding_interface_t

[comment]: <> (../inc/xrn_encoder.h)
```Xoronos_C
typedef struct xrn_encoding_interface_t {
     xrn_encoding_param_t i_encoding_param;
     xrn_encoding_param_t o_encoding_param;
} xrn_encoding_interface_t;
```

The **i_encoding_param** field is the input encoding parameters.

The **o_encoding_param** field is the output encoding parameters.

### xrn_interface_settings_t

[comment]: <> (../inc/xrn_encoder.h)
```Xoronos_C
typedef struct xrn_interface_settings_t {
     xrn_encoding_settings_t i_settings;
     xrn_encoding_settings_t o_settings;
} xrn_interface_settings_t;
```

The **i_settings** field is the input encoding settings.

The **o_settings** field is the output encoding settings.

## Encoding Decoding Functions

### xrn_encode

**Description:**

The **xrn_encode** is used to encode a stream of bytes.

**Function declaration:**

[comment]: <> (../inc/xrn_encoder.h)
```Xoronos_C
int xrn_encode ( 
    xrn_encoding_param_t * encoding_param,
    uint8_t plain_message[], 
    uint8_t enc_message[], 
    uint64_t message_length,
    xrn_encoding_tmp_param_t * tmp
);
```

**Arguments description:**

> **inout:**  encoding_param $\rightarrow$ The encoding parameters pointer. \
> **input:** plain_message  $\rightarrow$ The plain message vector. \
> **output:** enc_message    $\rightarrow$ The encrypted message vector. \
> **input:** message_length $\rightarrow$ The length for both plain and encrypted messages. \
> **inout:**  tmp            $\rightarrow$ Temporary variables used for optimization reasons. 

[comment]: <> ( docautocomplete xrn_encode  )

### xrn_decode

**Description:**

The **xrn_decode** is used to decode a stream of bytes.

**Function declaration:**

[comment]: <> (../inc/xrn_encoder.h)
```Xoronos_C
int xrn_decode (
    xrn_encoding_param_t * encoding_param,
    uint8_t enc_message[],
    uint8_t plain_message[], 
    uint64_t message_length, 
    xrn_encoding_tmp_param_t * tmp
);
```

**Arguments description:**

> **inout:**  encoding_param $\rightarrow$ The encoding parameters pointer. \
> **input:** enc_message    $\rightarrow$ The encoded message vector. \
> **output:** plain_message  $\rightarrow$ The decoded message vector. \
> **input:** message_length $\rightarrow$ The length for both plain and encrypted messages. \
> **inout:**  tmp            $\rightarrow$ Temporary variables used for optimization reasons. 

[comment]: <> ( docautocomplete xrn_decode  )

### xrn_check_randomness

**Description:**

The **xrn_check_randomness** is used to initialize xrn_encoding_param_t before encoding/decoding a stream of bytes.

**Function declaration:**

[comment]: <> (../inc/xrn_encoder.h)
```Xoronos_C
int xrn_check_randomness ( 
    uint8_t enc_byte, 
    xrn_encoding_param_t * enc_param,
    xrn_encoding_tmp_param_t * enc_param_tmp
);
```

**Arguments description:**

> **input:** enc_byte          $\rightarrow$ The byte to be inserted in the buffer and checked. \
> **inout:**  encoding_param    $\rightarrow$ The encoding parameters pointer. \
> **inout:**  enc_param_tmp     $\rightarrow$ Temporary variables used for optimization reasons. 

[comment]: <> ( docautocomplete xrn_check_randomness   )


### xrn_initialize_encoding_settings

**Description:**

The **xrn_initialize_encoding_settings** is used to initialize xrn_encoding_settings_t with the default values.

**Function declaration:**

[comment]: <> (../inc/xrn_encoder.h)
```Xoronos_C
int xrn_initialize_encoding_settings ( 
    xrn_encoding_settings_t * encoding_settings
);
```

**Arguments description:**

> **output:** encoding_settings $\rightarrow$ The initialization settings. 

[comment]: <> ( docautocomplete xrn_initialize_encoding_settings  )


### xrn_initialize_encoding_parameters

**Description:**

The **xrn_initialize_encoding_parameters** is used to initialize xrn_encoding_param_t before encoding/decoding a stream of bytes.

**Function declaration:**

[comment]: <> (../inc/xrn_encoder.h)
```Xoronos_C
int xrn_initialize_encoding_parameters ( 
    xrn_encoding_param_t * encoding_param,
    xrn_encoding_settings_t encoding_settings
);
```

**Arguments description:**

> **output:** encoding_param    $\rightarrow$ The encoding parameters pointer. \
> **input:** encoding_settings $\rightarrow$ The initialization settings. 

[comment]: <> ( docautocomplete xrn_initialize_encoding_parameters  )

### xrn_initialize_encoding_parameters

**Description:**

The **xrn_permute_encoding_param_with_pass** is used to initialize xrn_encoding_param_t with a password.

**Function declaration:**

[comment]: <> (../inc/xrn_encoder.h)
```Xoronos_C
int xrn_permute_encoding_param_with_pass( 
    xrn_encoding_param_t in_encoding_param, 
    uint8_t password[XRN_ENC_PASS_BUFF_SIZE], 
    uint16_t password_length, 
    xrn_encoding_param_t * out_encoding_param 
);
```

**Arguments description:**

> **input:** in_encoding_param $\rightarrow$ The input encoding paramethers. \
> **input:** password $\rightarrow$ The input password bytes. \
> **input:** password_length $\rightarrow$ The bytes used in the password. \
> **output:** out_encoding_param $\rightarrow$ The output encoding parameters pointer. \

[comment]: <> ( docautocomplete xrn_permute_encoding_param_with_pass  )

**Description:**

The **xrn_permute_encoding_param_with_file** is used to initialize xrn_encoding_param_t with a file.

**Function declaration:**

[comment]: <> (../inc/xrn_encoder.h)
```Xoronos_C
int xrn_permute_encoding_param_with_file( 
    xrn_encoding_param_t in_encoding_param, 
    FILE * fp,
    xrn_encoding_param_t * out_encoding_param 
);
```

**Arguments description:**

> **input:** in_encoding_param $\rightarrow$ The input encoding paramethers. \
> **input:** fp $\rightarrow$ The input file pointer. \
> **output:** out_encoding_param $\rightarrow$ The output encoding parameters pointer. \

[comment]: <> ( docautocomplete xrn_permute_encoding_param_with_pass  )

### xrn_initialize_encoding_interface

**Description:**

The **xrn_initialize_encoding_interface** is used to initialize xrn_encoding_interface_t before encoding/decoding a stream of bytes.

**Function declaration:**

[comment]: <> (../inc/xrn_encoder.h)
```Xoronos_C
int xrn_initialize_encoding_interface ( 
    xrn_encoding_interface_t * encoding_interface, 
    xrn_interface_settings_t encoding_settings
);
```

**Arguments description:**

> **output:** encoding_param    $\rightarrow$ The encoding parameters pointer. \
> **input:** encoding_settings $\rightarrow$ The initialization settings. 

[comment]: <> ( docautocomplete xrn_initialize_encoding_interface  )

### xrn_compare_encoding_parameters

**Description:**

The **xrn_compare_encoding_parameters** is used to check if two encoding_param_t are equivalent.

**Function declaration:**

[comment]: <> (../inc/xrn_encoder.h)
```Xoronos_C
int xrn_compare_encoding_parameters ( 
    xrn_encoding_param_t encoding_param1, 
    xrn_encoding_param_t encoding_param2
);
```

**Arguments description:**

> **input:** encoding_param1   $\rightarrow$ The first encoding parameters. \
> **input:** encoding_param2   $\rightarrow$ The second encoding parameters. 

[comment]: <> ( docautocomplete xrn_compare_encoding_parameters  )


## Dump and Load Functions

### xrn_dump_encoder_parameters_wrapper

**Description:**

The **xrn_dump_encoder_parameters_wrapper** is used to initialize and dump the xrn_encoding_tmp_param_t data structure to a file.

**Function declaration:**

[comment]: <> (../inc/xrn_encoder.h)
```Xoronos_C
int xrn_dump_encoder_parameters_wrapper ( 
    xrn_encoding_settings_t encoding_settings,
    FILE * fp 
);
```

**Arguments description:**

> **input:** encoding_settings  $\rightarrow$ The encoding settings. \
> **output:** fp                $\rightarrow$ The file pointer. 

[comment]: <> ( docautocomplete xrn_dump_encoder_parameters_wrapper  )

### xrn_dump_encoder_parameters

**Description:**

The **xrn_dump_encoder_parameters** is used to dump the xrn_encoding_tmp_param_t data structure to a file.

**Function declaration:**

[comment]: <> (../inc/xrn_encoder.h)
```Xoronos_C
int xrn_dump_encoder_parameters ( 
    xrn_encoding_param_t param, 
    FILE * fp 
);
```

**Arguments description:**

> **input:** param          $\rightarrow$ The encoding parameters. \
> **output:** fp             $\rightarrow$ The file pointer. 

[comment]: <> ( docautocomplete xrn_dump_encoder_parameters  )


### xrn_load_encoder_parameters

**Description:**

The **xrn_load_encoder_parameters** is used to load the xrn_encoding_tmp_param_t data structure from a file.

**Function declaration:**

[comment]: <> (../inc/xrn_encoder.h)
```Xoronos_C
int xrn_load_encoder_parameters ( 
    xrn_encoding_param_t * param,
    FILE * fp
);
```

**Arguments description:**

> **output:** param          $\rightarrow$ The encoding parameters pointer. \
> **input:** fp             $\rightarrow$ The file pointer. 

[comment]: <> ( docautocomplete xrn_load_encoder_parameters  )

## Safety checks

### xrn_check_encoding_parameters

**Description:**

The **xrn_check_encoding_parameters** is used to check if the xrn_encoding_param_t data structure is in a valid state.

**Function declaration:**

[comment]: <> (../inc/xrn_encoder.h)
```Xoronos_C
int xrn_check_encoding_parameters (
    xrn_encoding_param_t enc_param 
);
```

**Arguments description:**

> **input:** enc_param      $\rightarrow$ The encoding parameters. 

[comment]: <> ( docautocomplete xrn_check_encoding_parameters  )

### xrn_check_encoding_settings

**Description:**

The **xrn_check_encoding_settings** is used to check if the xrn_encoding_settings_t data structure is in a valid state.

**Function declaration:**

[comment]: <> (../inc/xrn_encoder.h)
```Xoronos_C
int xrn_check_encoding_settings ( 
    xrn_encoding_settings_t enc_settings 
);
```

**Arguments description:**

> **input:** enc_settings   $\rightarrow$ The encoding settings. 

[comment]: <> ( docautocomplete xrn_check_encoding_settings  )

### xrn_check_encoding_interface

**Description:**

The **xrn_check_encoding_interface** is used to check if the xrn_interface_settings_t data structure is in a valid state.

**Function declaration:**

[comment]: <> (../inc/xrn_encoder.h)
```Xoronos_C
int xrn_check_encoding_interface ( 
    xrn_interface_settings_t enc_interface 
);
```

**Arguments description:**

> **input:** enc_interface  $\rightarrow$ The encoding interface. 

[comment]: <> ( docautocomplete xrn_check_encoding_interface  )


## Interface Functions

### xrn_fwrite_encoder

**Description:**

The **xrn_fwrite_encoder** is used to encode and write the buffer in a file.

**Function declaration:**

[comment]: <> (../inc/xrn_encoder.h)
```Xoronos_C
int xrn_fwrite_encoder ( 
    const void *ptr,
    size_t size, 
    size_t nmemb, 
    FILE * stream,
    xrn_encoding_param_t * enc_param 
);
```

**Arguments description:**

> **input:** ptr              $\rightarrow$ The pointer to the buffer to write. \
> **input:** size             $\rightarrow$ The size of the buffer to write for one element. \
> **input:** nmemb            $\rightarrow$ The number of elements. \
> **output:** stream           $\rightarrow$ The file pointer. \
> **inout:**  enc_param        $\rightarrow$ The output encoding parameters pointer. 

[comment]: <> ( docautocomplete xrn_fwrite_encoder  )

### xrn_fread_decoder

**Description:**

The **xrn_fread_decoder** is used to read and decode a file and store it into a buffer.

**Function declaration:**

[comment]: <> (../inc/xrn_encoder.h)
```Xoronos_C
int xrn_fread_decoder ( 
    void *ptr,
    size_t size,
    size_t nmemb,
    FILE *stream, 
    xrn_encoding_param_t * enc_param 
);
```

**Arguments description:**

> **input:** ptr              $\rightarrow$ The pointer to the buffer to write. \
> **input:** size             $\rightarrow$ The size of the buffer to write for one element. \
> **input:** nmemb            $\rightarrow$ The number of elements. \
> **input:** stream           $\rightarrow$ The file pointer. \
> **inout:**  enc_param        $\rightarrow$ The input decoding parameters pointer. 

[comment]: <> ( docautocomplete xrn_fread_decoder  )


### xrn_decode_encode_bytes

**Description:**

The **xrn_decode_encode_bytes** is used to encode and write the buffer in a file.

**Function declaration:**

[comment]: <> (../inc/xrn_encoder.h)
```Xoronos_C
int xrn_decode_encode_bytes (
    uint8_t *in_bytes,
    uint8_t *out_bytes,
    uint64_t in_offset,
    uint64_t nbytes,
    xrn_encoding_interface_t * interface 
);
```

**Arguments description:**

> **input:** in_bytes         $\rightarrow$ The pointer to the input buffer. \
> **input:** out_bytes        $\rightarrow$ The pointer to the output buffer. \
> **input:** in_offset        $\rightarrow$ The offset of the buffer, where the first byte will be written. \
> **output:** nbytes           $\rightarrow$ The number of bytes to write after the offset. \
> **inout:**  interface        $\rightarrow$ The input output encoding parameters pointer. 

[comment]: <> ( docautocomplete xrn_decode_encode_bytes  )


### End of the library

[comment]: <> (../inc/xrn_encoder.h)
```Xoronos_C
#endif
```


